# TacticalBattle Scripts
by
ShadowMamba

# Table of Contents:

# Introduction

Hello, and welcome to the guide for my scripts!

There aren't very many here at the moment, but I hope that will change in the future.

To load my scripts into your map pack, do the following:
Go to the Map pack settings.txt file
In the line that says load_scripts=, type in ShadowMamba
(If the line isn't there, then add it at the bottom.)
And there you go, they're now available to you!

Return to the Table of Contents.

## The Scripts

My scripts use strings, bools and percentages at the moment. You can separate multiple strings by using a vertical bar (|). This will allow the game to randomly pick between them and allows for greater customization.

Be sure that your map pack is converted up to parser version 10. Also be sure to only enter the script flags below where it says "script_flags" in the file in question.

### `death_sound`

Type: string

Useable with: units

This script will play the given sound upon the unit's death. The game already has this built in, but this script is useful when you have many units with the same death sound and different cursor sounds, so you don't have to copy the death sound time and time again and take up more space. Note that if you have a death sound already set with the unit's cursor sound and then put a death sound in the script, they will both be played.

Does not choose between random death sounds, but I will add this in the future if anybody wants it.
Example of the script: `death_sound dragon death`

Please note that if you have two files with the same name but a different extention, then it might be best for you to add the file extention onto the end of that sound in the script flag so the script will know which one you want to be used.

### `summon_random`

Type: string

Useable with: skills, items

This script allows for the summoning of random units, with the format unit name/other unit name. Seperate each unit name with the slash (/) symbol.

`Example: summon_random demon/water demon/ice demon`

There are a few flags that can be used along with this script, if desired. Please note that they won't work if you try to use them without using summon random.

#### `summon_rare_random`

Type: string

Useable with: skills, items

This allows for the summoning of more rare units. When used alongside the summon random flag, this will be successful if given a chance, as shown in the next section.

The format of this flag is the same as with summon random. This means that to have the game choose between multiple rare random units, seperate each one with the slash (/) symbol. This script will not work without the summon random rare chance flag, which is shown below.

##### `summon_rare_random_chance`

Type: percent

Useable with: skills, items

To be used alongside the summon rare random flag, this flag causes the rare unit to be summoned with a success rate of whatever the defined percentage is. If used without this flag, the summon rare random script will not work.

Example:`
summon_random orc warrior/orc archer
summon_rare_random orc commander/orc king
summon_rare_random_chance 1%`
This means that there is a 1% chance of summoning an orc commander or an orc king instead of an orc warrior or an orc archer.

#### `apply_effects`

Type: string

Useable with: skills, items

When used alongside the apply effects chance flag, this will allow you to apply an effect, a list of effects, or a random selection of effects to the target.

`Example 1, single effect
apply_effects stun`

`example 2, a list of effects
apply_effects slow,bleeding`

`example 3, applying a random selection of effects
apply_effects stun,burn|stun,freeze`
This one basically allows you to have the effects that are applied be random. Useful for multi-elemental skills, when you only want one effect out of a selection being applied.

Please note that this script currently only works alongside the apply effects chance flag, shown below.

Also, these flags can be used outside of summoning skills/items, and they work in the same way.

##### `apply_effects_chance`

Type: percent

Useable with: skills, items

Similar to the other chance flags; put in a percentage, and that's the chance that the effects will be applied.

#### `add_random_skills`

Type: string

Useable with: skills, items, units

This script allows you to add either a single random skill, or a random selection of skills, to your newly-summoned unit. Since I designed this to make entire skillsets, use the comma to seperate skills you want in a set, the vertical bar to randomize between two or more skills in a set, and a semicolon to have the AI choose a random set of skills. This script can also be placed in a unit file and it will affect each one of that unit on the map instead of only the one that has been summoned.

`Example of a single random skill:
add_random_skills earthquake|tidal wave|lightning strike`

`Example of multiple random sets of skills:
add_random_skills earthquake,tidal wave,lightning strike|fireball,icebeam,wind blast
Example of a few different sets:
add_random_skills fireball,fire blast|firewall,fire shield,fire immunity;water jet,tidal wave,water immunity`

There is a subflag that you can use in conjunction with this, if you wish. It works regardless of what type of string you choose to use.

##### `add_random_skill_chance`

Type: percentage

Useable with: skills, items, units

This allows for greater customizability with my add random skills script flag. If you have this alongside it, you can choose the chance of a random skill, or set of skills, being added to the unit, whether it is being summoned or not. Put in a percentage, between 1 and 100 (such as 12%).

Note that you can't choose the chance for each individual skill or set appearing, just a skill or set in general.

`Example:
add_random_skill healing touch|destructive wave
add_random_skill_chance 50% // this means there is a 50% chance of a skill appearing. Since there are two skills here, then there is a 25% chance of getting a particular skill`

#### `summon_success_message`

Type: string

Useable with: skills, items

Similar to Craig Brett's success message script, this will play a message after the successful summoning. When writing the message for the skill, use {0} for the summoner and {1} for the summonee. If writing the message for an item, use {0} for the summoner, {1} for the item, and {2} for the summonee.

`Example: summon_success_message {0} summons a {1}
will be read as, if a good hero is summoning an ogre
The good hero summons a good ogre.`

This is, of course, only intended for the summon random script. If you want a success message for other skills or items, use Craig Brett's success message instead. Currently his success message script doesn't work in combination with my summon random script, hence why I made my own message for it.

#### `summon_success_sound`

Type: string

Useable with: skills, items

Plays a sound when the summoning is successful. Currently only works with a single sound, but I'll change that if requested.

### `apply_sound`

Type: string

Useable with: effects

Plays a sound when an effect has been applied, whether it be by a skill, item, or some other method. Use spaces in place of underscores, as usual.

### `apply_message`

Type: string

Useable with: effects

Says a message after an effect has been applied, whether it be by a skill, other effect or something else.

There are placeholders here too; for unit effects, {0} for the source of the application -- the user of the skill, for example -- and {1} for the target unit. If the effect is a tile effect, then {0} is for the source, if any, and {1} will read out as "1", so it's best to not use it there.

Example:
For a unit effect
apply_message {0} surrounds {1} with a cloud of dense fog.

### `removal_sound`

Type: string

Useable with: effects

Plays a sound when an effect has been removed, whether it be by a skill, item, or some other method. Use spaces in place of underscores, as usual.

### `removal_message`

Type: string

Useable with: effects

Says a message after an effect has been removed, whether it be by a skill, other effect or something else.

There are placeholders here too; for unit effects, {0} for the source of the removal -- the user of the skill, for example -- and {1} for the target unit. If the effect is a tile effect, then {0} is for the source, if any, and {1} will read out as "1", so it's best to not use it there.

Example:
For a unit effect
removal_message {0} removes flying from {1}.
For a tile effect
removal_message The water from {0}'s attack causes the blazing fire to be extinguished.

### `start_turn_sound`

Type: string

Useable with: effects

This script will play a sound for unit effects at the beginning of the turn, for as long as the effect is in existence. Note that it currently only works with effects that are placed on units. I haven't yet figured out how to get it to work with tiles.

Supports random sounds, similar to the cursor examples in the map creation guide.

### `end_turn_sound`

Type: string

Useable with: effects

This script will play a sound for unit effects at the end of the turn, for as long as the effect is in existence. Note that it currently only works with effects that are placed on units. I haven't yet figured out how to get it to work with tiles.

Supports random sounds, similar to the cursor examples in the map creation guide.

### `create_items`

Type: string

Useable with: skills, items

This script will create an item, or multiple items, upon the successful performing of a skill or use of an item. The format is item1,item2|altItem1,altItem2. The vertical bar separates alternatives. In this case, alternative item(s) to be created. If you want more than one item to be made at once, then you can separate each individual item with a comma.

If the skill or item targets a unit, the items will be placed directly in the unit's inventory. If targeting a tile with a unit on it, then the same will happen. If targeting an empty tile, the items will be placed on the tile, ready for pickup. For best use of the script, I recommend specifying either empty_tile or else one of the unit flags.

Example:
create_items scroll of summoning,minor healing potion|long bow
This means that the game will either create both the scroll of summoning and the minor healing potion, or the long bow.

There are a few other flags that can be used alongside this one.

#### `create_item_on_failed_use`

Type: bool

Useable with: items

Place this in an item file. If the use of that item is unsuccessful, then the item will be placed on the target tile.

If you use this script, be sure to have create_items specified as well, else it will not work and you'll get an error.

Personally, I see this script to be useful when you, say, throw a dagger at an opponent. If it misses or whatever, then the dagger, as in reality, will be lying on the ground, ready for pickup.

#### `create_items_chance`

Type: percent

Useable with: items

Use this alongside the create items script flag in order to specify the chance that an item should show up.

#### `create_rare_items`

Type: string

Useable with: items

This flag allows for the creation of rare items instead of what the skill or item can normally create. It has the same format as the create items flag. This will only work if used alongside the chance flag.

##### `create_rare_items_chance`

Type: percent

Useable with: items

Use this alongside the create rare items script flag in order to specify the chance that a rare item should show up instead of a normal one.

### `remove_flying`

Type: bool

Useable with: items, effects

Place this in an effect file, or in the file of an item that is to be equipped, and it will temporarily remove the unit's ability to fly. This is reversed if the item is unequipped, or the effect fizzles or is removed.

Note that this doesn't work for remove effects that cause flight. If you want to remove a unit's flying effects, then you have to do that separately. This is only meant to be used if a unit has "flying" specified in their unit file.

### `grant_flight_on_equip`

Type: bool

Useable with: items

This script grants flight for the unit for as long as the item is equipped. Keep in mind that this is not done through an effect! Flight is removed from the unit once you unequip the item. If you also have an effect that is causing flight, then the effect, and flying from said effect, may still be present.

### `aditional_description`

Type: string

Useable with: skills, items, effects

This script allows for aditional descriptors to be added before the unit's friendly name, for as long as the effect lasts. For example, if a spaceship uses a cloaking skill, instead of being read out as "the spaceship", the game will read out "the cloaked spaceship" as long as that's what you specify. When the effect fizzles or is removed, the descriptor given by that effect will also be removed.

If used alongside a skill or item, the descriptor is permanently added and can only be removed if the remove aditional descriptor flag is used.

`Example:
aditional_description stunned`

### `remove_aditional_description`

Type: string

Useable with: skills, items

This script removes the specified aditional descriptor from a unit, if it is present. Useful for when you added a descriptor with a skill or item and now want to remove it.

### `random_name`

Type: string

Useable with: units

This script will give units a random name, choosing from any in the list that you specify. The format is name1|name2, where the names are separated by a vertical bar (|) symbol.

Not really useful, but for greater customizability I guess some might like it.

### `apply_effects`

Type: string

Useable with: skills, items

If used alongside the apply effects chance flag, this script allows you to apply an effect, a list of effects or an assortment of random effects to the target.

Example:
apply_effects burn|freeze|shock // this causes any of the three effects, burn, freeze or shock to be applied, assuming the chance flag is also set.
apply_effects stun,burn // Applies both the stun and burn effects to the target.

### `apply_effects`

Type: percent

Useable with: skills, items

### `remove_effects`

Type: string

Useable with: skills, items

When used alongside the remove effects chance flag, this will allow you to remove an effect, a list of effects, or a random selection of effects from the target.

`Example 1, single effect
remove_effects stun`

`example 2, a list of effects
remove_effects slow,bleeding`

`example 3, removing a random selection of effects
remove_effects stun,burn|stun,freeze`
This one basically allows you to have the effects that are removed be random.

Please note that this script currently only works alongside the remove effects chance flag, shown below.

#### `remove_effects_chance`

Type: percent

Useable with: skills, items

Similar to the other chance flags; put in a percentage, and that's the chance that the effects will be removed.

### `steal_item`

Type: bool

Useable with: skills, items

Major thanks to Craig Brett and keyWasFull for helping me to get this one off the ground!

This script is useful for the classic thief. Place it in a skill or item file, and when the skill or item is successfully used on a target, it will attempt to steal an item that is in the target's inventory. It only steals one item at a time, so if you want to empty them out then you've got to use it multiple times. If there are no more items to be stolen from the target, the script will say:
"This unit does not have any items to steal."

`Example:
steal_item`

### `steal_item_message`

Type: string

Useable with: skills, items

This works the same as any other success message. Input {0} for the source of the skill, {1} for the target, and {2} for the item that has been stolen.

`Example:
steal_item
steal_item_message {0} snatches a {2} from the pocket of {1}.`

### `random_inventory_items`

Type: string

Useable with: units

This code will create random items in the unit's inventory, after the map has been loaded or after it has been placed by other means, such as via summoning. The format name is item1/percentChance,item2|alternateItem2/percentChance,item3;item4;item5. If you want multiple items with the same percentage chance, separate them with a vertical bar and then follow by the percent chance. If you don't specify a percentage, then that item has a 100% chance of appearing. If you want certain items to be added together, seperate them with the comma. If you want sets of items appearing together, seperate each set with the semicolon and the individual items in the set with commas.

`Example:
random_inventory_items shortsword|longsword|bastard sword/50%;long bow,quiver of arrows|crossbow,quiver of bolts/25%;club|spear|axe/25%;dagger;chainmail shirt`

### `after_damage_sound`

Type: string

Useable with: units

This script allows for units to vocalize their agony!

Basically, you can choose a point, and then if that point is damaged, it will play the specified sound.

The format is the name of a point, followed by a colon, followed by the desired sound. If you want multiple points to play the same sound, then seperate the points with the vertical bar symbol. If you want to play two sounds that have different names, seperate them with the vertical bar symbol.

`Example:
after_damage_sound health|life force:orc pain|orc archer pain`

If you want to identify points that should play different sounds, then the format is pointname:sound,pointname2:sound2. The format for randomization is the same as before.

`Example:
after_damage_sound health:dwarf pain,soul:dwarf scream`

### `source_effects_after_damage`

Type: string

Useable with: units

This causes an effect, or a list of effects, to be applied to the source unit -- if any -- when the target takes damage.

The format is the point name, followed by a colon, then any effects (randomize with the vertical bar, seperate individuals with a comma). Note that the script supports both unit and tile effects. If you want to have a limited chance of the effects being applied, then after the final effect name put another colon, followed by the chance in percentage form.

To set it so that the effects will only be applied if the source is within a certain range, place another colon after chance -- you need chance for range to work -- then input the range.

`Examples:
Simple effect application
source_effects_after_damage health:burn
Multiple effect application
source_effects_after_damage health:burn,inferno
multiple points for the same effect, and random effect application
source_effects_after_damage health|life force:burn|freeze|static
Certain chance of any effect appearing
source_effects_after_damage health:freeze:10%
Multiple points with different effects
source_effects_after_damage health:burn|freeze|static:10%; soul:icy chill:1%
With range
source_effects_after_damage health:burn:25%:2 // This means that burn will have a 25% chance of affecting the source, if the source is within two tiles of the target.`

### `target_effects_after_damage`

Type: string

Useable with: units

This script is nearly identical to the previous one. The only difference here is that instead of applying effects to the source of the damage, if any, they will be applied to the target instead. The format is the same, just replace "source" with "target" when doing the script flag. For obvious reasons, range is not recognized with this script flag.

### `random_damage`

Type: string

Useable with: skills, items

This script is meant to cause random damage to a target... Random as in, between different damage types. You can also use this to make the script choose randomly between different points, but the reason I made it was for the different damage types.

Can currently only be used to target a single unit... It does not work properly for skills, items or effects that target tiles, and not a unit directly. There is also no splash component, at least not yet.

The format is pointname:amount:typeOfDamage1|typeOfDamage2/pointname:amount:DifferentTypeOfDamage,differentPointname:amount:damageType. If the damage type is left unspecified, it will use the map pack's default.

`Examples:
Choose between multiple forms of damage
random_damage health:150:fire|ice
Damage multiple points at once
random_damage health:150:fire,actions:4/health:150:ice,movement:4`

### `drain_point`

Type: string

Useable with: skills, items

This script will drain an amount from an opponent's point, and transfer that amount to the user. So, if you want to use this script to drain health, it will take an amount from the target and give that amount to the user. Note that this script does not restore past maximum point values.

The format is pointname:valueToDrain:damageTypeIfYouWantToUseIt,pointname2:amountToBeDamagedHere|alternateDamageAmount. If you don't specify a damage type, the map pack's default damage type will be used.

`Example:
drain_point health:25:fire,actions:1 // This'll do 25 fire damage to the target, and give the source 25 health back. It'll also restore an action point.
drain_point health:25|50|75 // This will drain 25, 50 or 75 health from the target, and restore that same amount to the user.`

### `counter_attack`

Type: string

Useable with: units, passive skills

Finally, counter-attacking is available!

This flag, and the chance, message, range and sound flags, can be placed in unit and passive skill files.

The format of this flag is pointname:amountOfDamage:damageType. The point is what you will damage when countering, the amount can be used as a solid, dice or range like normal point_inflict flags, and the damage type is the type of damage you want to do. If not specified, then the damage type will be whatever the default one is in your map pack. If you want to damage multiple points at once, place a comma after the damage type, then input what you want done.

`Examples:
Simple counter
counter_attack health:25d3:slashing
Multiple points
counter_attack health:25d3|shadow,life force:25d3:shadow`

#### `counter_attack_chance`

Type: percent

Useable with: units, passive skills

Place this in a unit or passive skill file, and choose a percentage from 1 to 100. You cannot successfully use the counter attack script without this flag.

`Example:
counter_attack_chance 20% // This means that when being hit, a unit has a 20% chance of countering right away.`

##### `counter_attack_chance_mod`

Type: percent

Useable with: equipped items, effects

This code can be used to increase or decrease the chance of a unit counter-attacking.

`Example:
counter_attack_chance_mod -15%
This causes the unit to have a 15% less chance at successfully countering.`

#### `counter_attack_range`

Type: int

Useable with: units, passive skills

Choose the range that the source has to be within in order for your target to be able to counter. If the source isn't close enough, no counter will be attempted. This flag is necessary for the counter attack script to work.

`Example:
counter_attack_range 1 // Means that the counter only happens when the source is within a tile's reach of the target`

#### `counter_attack_cost`

Type: string

Useable with: units, passive skills

Allows for there to be a point cost in order to perform a counter-attack. If the point doesn't have enough of the amount, no counter will occur.

The format is pointname:cost,alternatePointName:thatCost.

`Example:
Simple point cost
counter_attack_cost counter:1 // You can only counter if you have at least 1 counter point
And now, multiple points at once
counter_attack_cost actions:1,counter:1 // Both points need at least 1 current point to be able to counter.`

#### `counter_attack_damage_points`

Type: string

Useable with: units

This optional flag specifies the points that need to be damaged in order for your unit to counter. If not specified, your unit will counter when any point is damaged with an inflict flag.

`Example:
counter_attack_damage_points health,life force // This means that your unit will only counter when either their health or life force have been damaged`

#### `counter_attack_message`

Type: string

Useable with: units, passive skills

Says a message before the counter damage is read out. Use {0} for the unit doing the counter-attacking and {1} for the unit being countered. You can seperate alternative messages with the vertical bar.

`Example:
counter_attack_message {0} suddenly lashes out, viciously slashing {1} in retaliation.`

#### `counter_attack_sound`

Type: string

Useable with: units, passive skills

Plays a sound when counter-attacking.

`Example:
counter_attack_sound long sword`

#### `cannot_be_countered`

Type: bool

Useable with: units, skills, items, effects

This flag will prevent a unit from countering. If a unit has this flag, then they will never get countered. If a unit has an effect or equipped item with this flag in it, they cannot be countered for as long as the effect lasts or said item is equipped. If a skill has this flag, then countering will not occur when said skill is used.

This flag also has an impact on the source effects after damage script. If it is found anywhere on the source -- on an item (whether equipped or being used), effect, the unit file or the skill that is being used -- then the script won't apply effects to the source.

#### `cannot_counter`

Type: bool

Useable with: items,effects

Place this in an effect, and the affected unit is unable to counter for the duration that the effect lasts. Alternatively, if it is in an item file, the unit cannot counter for as long as the item is equipped.

### `switch_places`

Type: bool

Useable with: skills, items

This flag will take the source and target units and switch their positions, so that the target is where the source was and vise versa. Useful for rescue-type skills.

Does not work if there is no obvious target.

Return to the Table of Contents.

# Known Bugs

When you are flipping through the battle log and a unit's death sound is meant to be played, it will play on the line after the unit dies. This can be awkward when another unit is performing an action because the sounds will play at the same time. This can be fixed by also giving the unit a death message using Craig Brett's death message script.

When using the summon random script, there is currently no way to prevent the units from being summoned on terrain that they normally cannot move on. This can be problematic if a unit gets summoned inside of a wall, or in the middle of terrain that is impassable to them. Also, it seems that there are times where the skill or item is successful, but the summoning doesn't work. They're rare, so hopefully it won't be a big issue.

When using the random damage script and targeting a tile, damage is only done to one of the units on said tile. For this reason I would advise only using it to directly target units using the enemy flag in skills and items, and the unit flag in effects.

On counter attacking, a unit may counter right before it dies. I guess it's like a last stand kind of thing. I'm not sure how to remove it, so it stays for the time being.

Return to the Table of Contents.

# Credits

Although the idea for these scripts are mine, I did have quite a bit of help with their creation.

Lots of help came from Craig Brett and KeyWasFull, so major thank you's go to both of them! Hopefully I didn't bother the two of you too much. I would also like to thank Victorious for answering a few other questions that I had about scripting effects.

Finally, a thank you to Ian Reed for creating this game! Without it, I doubt I would have had the incentive to start trying to learn programming.